Current version 3.8.0 (2020-07)

Users' guide for V_Sim

Author: Damien Caliste, Olivier d'Astier & Luc Billard

This is an almost full documentation for V_Sim, describing many of the capabilities present in V_Sim.


  1. Basics
    1. The interface of V_Sim
    2. Load a file
    3. The rendering methods
    4. Interactions
    5. Drawing pairs
    6. Basic parameters
    7. Browsing through current directory
  2. Further representation and analysing tools
    1. Colourise nodes
    2. Draw planes & hide nodes
    3. Display surfaces
    4. Draw scalar fields as colour maps
    5. Animate phonons or molecule vibrations [TODO]
    6. Analyse evolution between files
  3. Miscellaneous
    1. Export to different formats
    2. Scripting capabilities [Update]
    3. Files


Interface - the two windows↑ Return to top

The interface is divided into two windows. The one where the image is rendered is called the rendering window. It shows the loaded file. A small status bar stands on its bottom and gives some informations. The second window is called the command panel. It hosts all tools available with V_Sim.

These two windows have different X names (under X11), then the window manager can be used to store their size and position (see 'advanced properties' of Kwin or 'remember' menu option in Fluxbox for instance).

From version 3.5, the two windows can be gathered into one, or the command panel may not be created:

Interface - the subpanels↑ Return to top

From version 3.3.0

All tools available in V_Sim are gathered in different tabs called subpanels. These tabs are all hosted by the command panel, but they can be detached to act as floating utility windows (as in Gimp or Inkscape for instance). To do it, click on the little arrow on the right side of a tab header. It opens a menu that propose to create a new dock window to host the subpanel, or it gives a list of existing docks to send the subpanel to. It is also possible to hide the subpanel if it is not useful. The characteristics of docks windows (which subpanel they contain, their screen position, their size...) can be saved to the parameter file (see the related section).

Here is the list of tabs (as of version 3.6) and their capabilities:

Interface - the command line options↑ Return to top

v_sim [options] [fileToRender]

The available options are detailed by typing 'v_sim --help', or 'man v_sim'.

The following table lists all the available options, their meaning and their syntax.

KeywordMeaningNew from
-e, --export filemake an image from the fileToRender argument. The format is specified through the extension of the argument or by the -o fileFormatId=id option (get the id of available file formats with -o list).version 3.0.0
-r, --resources fileload the given resources file on startup instead of looking for a valid resources file in the standard locations.version 3.4.0
-h, --helpshow this little help.version 3.0.0
-g, --geometry <w>x<h>
(Default value: 600x600)
specify the size of the rendering window, the size argument must have the following format: <width>x<height> with positive non null values.version 3.0.0
-s, --spin-file fileuse the given argument as a spin indicator. If this option is used, V_Sim switches automatically to spin rendering whatever method is specified in the parameter file.version 3.1.0
-m, --hiding-mode id
(Default value: 0)
policy used to show or not null modulus spins possible values are positives.version 3.2.0
-a, --spin-and-atomicalways draws atomic rendering on node position in addition to spin rendering.version 3.3.0
-c, --colorize {file,property#propName}the argument fileToRender must be called, then the given file of the option is used to colorize the elements. If argument is starting with 'property#', colorization data are taken from node property propName.version 3.1.0
-u, --use-column l:m:nit specifies the columns to use from the data file for the three colour channels [l;m;n]. Columns are counted from 1. Use -3, -2, -1 and 0 to use the special values, constant 1, coord. x, coord. y, and coord. z, respectively.version 3.1.0
-d, --color-preset idthis option can be used with the '--colorize' one or the '--build-map' one. It chooses a preset color scheme. The id argument is an integer that corresponds to a defined color shade (ranging from 0).version 3.1.0
-t, --translate x:y:za file must be loaded. It applies the given translations to the loaded file. The units are those of the file. This is available for periodic file formats only.version 3.3.0
-q, --box-translate a:b:ca file must be loaded. It applies the given translations to the loaded file. The translation is applied along box axis, normalised to 1. This is available for periodic file formats only.version 3.8.0
-x, --expand x:y:za file must be loaded. It applies the given expansion to the loaded file. The values are given in box coordinates. This is available for periodic file formats only.version 3.4.0
-p, --planes filethe argument fileToRender must be called, then the given file of the option is parsed as a list of planes and they are rendered.version 3.2.0
-f, --scalar-field {file,.}the argument fileToRender must be called, then the given file of the option is parsed as a scalar field and loaded. Use '.' as a special value to reuse the main filename.version 3.3.0
-v, --iso-values v[:v]must be used with the '--scalar-field' option, then the given surfaces are built and rendered. If a name is appended to a value using '#' as a separator, this name is used as the name for the iso-surface (i.e. 0.25#Blue). Use specific value 'auto' to compute isosurfaces at half max and min value.version 3.3.0
-i, --iso-surfaces filethe argument fileToRender must be given, then the given file of the option is parsed and surfaces are rendered.version 3.2.0
-b, --build-map id[:id]the argument fileToRender must be given, as the '--planes', '--color-preset' and '--scalar-field' options used, then the given plane 'id' is replaced by a coloured map using given scalar field and shade. 'id' ranges from 0. If several ids are given, several maps are built.version 3.4.0
--log-scale idselect the scaling method to use with gradients (0: linear, 1: log scaled and 2 is zero-centred log scale), default is linear scale.version 3.4.0
-n, --n-iso-lines valwhen positive, val isolines are plotted on the coloured map.version 3.4.0
--color-iso-lines [R:G:B] or auto
(Default value: [0:0:0])
when given, generated iso-lines are colourised [R:G:B] or auto with the values. The specific value 'auto' will produced iso-lines in inversed colours.version 3.5.0
--fit-to-box val
(Default value: TRUE)
if val is not TRUE, the surfaces use their own bounding box.version 3.3.0
--bg-image filedraw the given image on the background.version 3.4.0
-o, --option id=valuethis is a generic way to give extended option. to V_Sim. As much as -o can be used. Each one store a key and its value (boolean, integer or float).version 3.3.0
-w, --window-mode mode
(Default value: classic)
used to choose the windowing mode. By default the command panel and the rendering window are separated. In the 'oneWindow' mode they are joined. In the 'renderOnly' mode, the command panel is not used.version 3.5.0
--i-set i
(Default value: 0)
this flag is used to choose the id of the loaded file if the format has support for multiple ids in one file (see XYZ format or -posi.d3 ones).version 3.5.0
--value-file filespecify an XML file with some value information for V_Sim, like a list of planes, highlighted nodes... It replaces and extend the previous --planes option.version 3.5.0
--map-precision prec
(Default value: 100)
Give the precision in percent to render the coloured map.version 3.5.0
--map-clamp min:max or auto
(Default value: auto)
Set the minimum and maximum values for the coloured map rendering.version 3.6.0
--color-clamp col#min:max or auto
(Default value: auto)
Range to adjust values into for colourisation. col specifiesthe column to apply the range to. Use -2, -1 and 0 for x, yand z directions respectively.version 3.7.0
--scaling-column idused with a data file (see -c), it specifies the column id to be used to scale the nodes.version 3.7.0
--diff-from fileCompute the geometric difference between load file and this argument.version 3.8.0
--phonon-mode mode
(Default value: 0)
Load the given phonon mode.version 3.8.0
--time-offset offset
(Default value: 0)
Displace nodes according to phonons at the given reduced time in [0;1].version 3.8.0
--phonon-amplitude ampl
(Default value: 1.)
Maximum displacement for phonons.version 3.8.0

Usage↑ Return to top

There are three ways in V_Sim to open a crystal file (available formats are described later):

Change the units of a file↑ Return to top

From version 3.5.0

If the file format gives unit information to V_Sim, the selector in the box subpanel will show the right value. If one select another unit, the corresponding factor will be applied on node positions and box size. All other values are kept equal. For instance, this is useful when all configuration files have been set up for Bohr units (pairs criterions...) but the loaded file is in angstöms.

In the configuration subpanel, one can choose his favorite unit. So when a file is loaded, the units are changed to always reflect this favorite value. This value is saved in the parameter file.

When the file format does not advertise any unit value, V_Sim is set to "undefined". The next selection of a unit will internally set the unit to this new value. Then one can do convertion as explained in the first paragraph.

Unit are exported when using a file format that can support it.

Translate and expand box↑ Return to top

From version 3.4.0

In the box subpanel, and if the input file has periodic boundary conditions, the rendered system can be translated or expanded. For instance, XYZ files has no periodic information and these capabilities are disabled. The values for translation can vary from -1 to 1. and are given in reduced coordinates. The value for the expansion corresponds to the number of box duplication in each direction, both positive and negative. Float values are accepted. When the box is expanded, translation are kept but can be changed anymore. Uncheck the expansion to be able to change the translations again.

Expansion and translation are available from command line:

Automatic update↑ Return to top

From version 2.3-4

When this option is enabled (see "configuration" subpanel), the program probes the disk for file changes and updates the drawing if necessary. The period for polling is adjustable and can vary from 100ms to 10s.

Max number of atoms↑ Return to top

There is NO max number of atoms. But, of course, if you visualize an atomic file with many atoms, drawing may become long time consuming thus, changing values on command panel may become difficult, because in "Immediate drawing mode", any change of values lead to a draw with the new values. In this case, use "Deferred drawing mode", and, when you have chosen your favourite values, use button "Redraw".

The program does not support more than NMAX_TP atom types (current implementation has NMAX_TP = 500). If you wish more, please contact Damien Caliste (damien.caliste A

The Rendering Atomic method - file formats↑ Return to top

V_Sim visualizes atomic files:

The Rendering Atomic method - rendering shapes↑ Return to top

From version 3.0.0

Elements can be rendered as spheres, which is the default behaviour. But other shapes are available. When a huge amount of elements must be rendered and look is not very important, one can choose the cubic shape or even the point shape. This last mode can be convenient also for representing grid points. The last available shape is the ellipsoid one. It can be used to make schemes when a direction must be highlighted. See the "Element" subpanel to change the shapes (1).

The orientation of the ellipsoid shape shape can be tuned per element (see (2)). Thus if orientation is important for each node of a given element, the spin method is more appropriated.

From version 3.5, a torus shape is also available. It follows the parameters of the ellipsoid shape. The two angles are used to orientate the torus. The main radius of the torus is the radius of the element and the ratio is used to obtain the internal radius.

The Rendering Spin method - Overview & basic options↑ Return to top

From version 3.1.0

V_Sim can display spin configurations. Spin are represented as arrows, oriented and coloured according to the spin orientation of the node they represent. For each element arrow, you can specify many parameters such as its size, color or shape.

To set up V_Sim in "Spin Visualisation" mode, you must select this mode under the "Rendering method" subpanel (1). When this mode is selected, options relative to other modes are removed, and new ones appear, in this subpanel and in the "Element" one. You can then try to load a spin configuration to display.

The spin visualisation has several option. Basically elements can be represented by arrows, but atomic rendering can also be present when checkbox (2) is checked. By default, the modulus of spin is ignored. This behavior can by overridden with checkbox (3). When checked, the modulus is normalised to match the selected maximum length for arrows. The normalisation can be done per node types or for all of them. Finally, one can tune how spin with null modulus can be rendered (4): never (show elements with positive spin values), atomic (replace arrow by atomic rendering) or always (don't take care about modulus value).

The Rendering Spin method - Loading files↑ Return to top

From version 3.1.0

To load a spin configuration (1), V_Sim reads two separate files. The first one is a "position file" (2), which contains each atoms position. Supported formats are exactly the same as the ones supported by the "Atomic Visualisation" mode (see the Atomic Visualisation mode documentation for more details). The "spin file" (3) contains each atoms spin information.

The Rendering Spin method - Coloration options↑ Return to top

From version 3.1.0

Once you've selected your files, you should have your atomic configuration displayed on the screen. The first thing to understand is the bottom right color legend. Spins are coloured according to the HSL color space which is often represented as a "double conical" space. This cone is drawn to the bottom right of the screen if you chose to enable the axes. Two coloured areas are needed to get an exhaustive legend (1 & 2). The upper part represent the hidden area of the color cone (seen from the interior of the cone) (2).

You can set up coloration options under the "Config panel" (you need to click the "Show rendering option" label). "Rotate color wheel" (3) causes the cone to turn around its own rotation axis whereas the other options (4) allow the user to set the direction of this axis (in the main referential's coordinates). The "set ortho" button (5) sets the cone' axis to the current viewing direction. Notice all these options are saved along with the resources.

The Rendering Spin method - Elements options↑ Return to top

From version 3.1.0

As in the "Atomic visualisation" mode, viewing options for each element can be set under the "Element" panel. From there, arrow properties can be changed according to user preferencies (1). Note they are saved along with resources. If you prefer to use normal coloration over spin coloration for an element, check the "Use element color for the ..." buttons (2). The available shapes are smooth arrows, edged arrows, ellipsoids (from version 3.2) and torus (from version 3.5).

Tip : the "Edged" shape for the arrow may seem ugly but it is a lot lighter than the "Rounded" shape, so try to use it if V_Sim is too slow on your computer. Notice the "Edged" shape is unaffected by the precision parameter set under the "Opengl" panel.

The Rendering Spin method - Command line options↑ Return to top

From version 3.1.0

Moving the camera↑ Return to top

From version 3.2.0

The main interface of V_Sim is divided into two windows: the command panel and the rendering window. On this last window, the mouse is used to move the camera. This is called the observe mode. These mouse actions are possible:

Possible actions are summed up in the status bar on the bottom of the rendering window (2). It mentions that a simple pick action is available. To get informations on nodes right click on them. Available data are coordinates and node number. Distance can be directly measured in this default view, using the shift key + a right click. This will set a reference from which all further picked nodes will be compared to. To unset this reference, shift right click on nothing. From version 3.5, use control to set a second reference for angle measurements, and control + shift of shift for distance measurements, to be coherent with to hightlight a node.

The status bar contains also global informations (3) such as the window size or the number of nodes in the currently rendered file. If any commentary is present in the file, it is shown here. The buttons (4) are used to open a file (identical as the "open" button in the command panel), to refresh the view, to export the view in a bitmap format (or others if available) and the last is used to raise the command panel. From version 3.5, the refresh button is used to reload the file instead.

From version 3.5, there are there three icons on the right bottom part of the rendering window, as shown on the right.

The interactive window↑ Return to top

By clicking on the "pick & obs." button on the command panel, this last is replaced by a new window. This window gives access to detailed interactive mode. The most basic is the observe mode. It allows to move the camera as in default mode (when the command panel is presnt) but with access to detailled values. By right clicking, on can switch to another interactive mode, present in the current tab (1).

There are two observe mode (2):

In the bottom of this window, a small help frame (3) is present and always sum up the possible actions, whatever the current mode.

Playing with pick↑ Return to top

You can use several modes (all actions are detailed in the help frame). Picked information will then be printed into the area (1). Keyboard modifiers have been changed from version 3.5 to be coherent with the minimal pick mode of the rendering window in normal mode.

All measured distances and angles are persistent. A line is drawn between nodes and the length is printed in the middle of the line. For angles, a small filled arc is also drawn with the angle value in degrees. To avoid this, uncheck the box (2) on the bottom of the pick tab. One can also remove all marks by clicking the "clear" button near this checkbox.

A table of picked nodes is kept (3). Use the Suppr key to remove a node from this history (this does not remove the node itself). The number and the type of the node is printed. Some other informations may appear, such as the spin orientation informations in spin mode (values are then changeable). The colour data is also print there, if any colour file has been loaded (see the colourise nodes entry). The checkbox of the second column is active if the node is highlighted. Use the buttons near (6) to highlight or unhighlight all the nodes in the history list.

The widgets on (4) are used to draw information directly on the rendering area. One can choose to draw data only on nodes listed in the above table or on all nodes. In version 3.5, for ASCII files, a label can be drawn on whatever node.

From version 3.5, the buttons in area (5) can be used to load or save an XML file containing a list of picked nodes. The highlight status and all distances can be stored in such a file also.

In any mode, right-button ends picking session and returns to observe mode.

Geometry modifier↑ Return to top

This is a simple interface to change the geometry. By left clicking on a node, it is possible to move it in the view plane or constrained along X, Y or Z axis (see the help frame for further explanations). This mode is convenient with the export to ASCII since then, the modified geometry can be saved into a file (use the export button and choose the ASCII export format). It is also possible to move several nodes at once. To do it, change the radio buttons (1) accordingly. The selected nodes are those that appear in the table (3) of the pick tab (see above).

Still on the geometry tab, one can add new nodes at a given position. Only chemical species already existing can be added. To remove nodes, pick one or several and click the minus button. Warning, it is not possible to cancel the removal (except when only one node has been removed).

Changing the basis set↑ Return to top

From version 3.5.0

It is possible to change the basis set, i.e. define another bounding box, by selecting nodes that would be at vertices of the new basis set. The new origin is called O in the interface and the vertices at x, y and z directions are respectively called A, B and C.

One can choose the new vertices either by giving their id (see (1)) or by picking them directlty (see (2)). When the four vertices are chosen, one can apply the new basis set by clicking the apply button (3). All nodes outside the new box will be suppressed. This action cannot be undone.

From version 3.6, when the the four vertices are chosen, V_Sim draw lines along the new directions to give an idea of the new basis set. A warning can also be issued if the basis set would be indirect (see (4)).

Symmetry analyser↑ Return to top

From version 3.5.0

When the ABINIT plug-in for V_Sim is compiled and loaded, there is a new tab in the inderactive dialog (see (1)). By default, the symmetries are not computed, to do it, click on the button (2). If the box is a primitive one, the corresponding space group and crystal symmetry are displayed near (3). Using a node id, or by clicking on one atom, one can highlight the equivalent atoms by symmetry, see (4).

From version 3.6, a list of symmetry operations are also listed with their names in a treeview near (3). One can also tune the tolerance on symmetry calculation, as defined by tolsym in ABINIT.

Drawing pairs↑ Return to top

To use pairs, it is mandatory to check the toggle button at the bottom of the main command panel, next to the "pairs" button. This last button is used to open a dialogue window to customise pair definitions.

The pair dialogue is used to create pairs and choose their characteristics and rendering aspects. Two pair models are available (see further).

The table (2) is used to list all possible pair definitions. In V_Sim, pairs are characterised by the two chemical species of elements they link, plus the distance in-between they are drawn. On the given example, pairs are drawn between all Mn and Ge nodes which distance is in 2.5 and 2.6. Since version 3.4.0, it is possible to define more than one distance criterion for a given chemical species couple (use buttons (4)). When a great number of chemical species are present, one can filter the list with the combobox (3). One can also (since version 3.5) use the toggle button (6) to hide all pair definitions that give no drawable pairs (min criterion greater or equal to max criterion).

The 'automatic' button (5) can be used to compute first neighbour pairs. Select one or more line in the table (2) and click the button (5). V_Sim compute the distance distribution for each selected line and take the distance boundaries that define the first pick in the distribution.

In the table (2), the first checkbox column is used to render or not a defined pair. The second checkbox column is used to print on the rendering area the distance of all pairs.

From version 3.6, pair style can be chosen per link, as shown on the right image. This is convenient to use pair links to highlight bonding characteristics like weak hydrogen bonding.

Drawing pairs as wires↑ Return to top

The wire pair rendering method draws pairs as simple flat lines. One can tune the width in pixels (1) and the line pattern (2). In addition, one can choose to colourise (3) the pairs according to their length (this choice is applied for all wire pairs).

Drawing pairs as cylinders↑ Return to top

The cylinder pair rendering method draws pairs as 3D cylinders. With the cylinder, it is possible to change the diameter (1) and an option (2) can be used to draw the pair in the colour of the element it represents instead of a specific one. In the former case, the bond is separated into two.

Analyse pair length distribution↑ Return to top

From version 3.6.0

V_Sim can plot a distribution of pair length, also called g(r). The pair dialog has a new tab, called "distances" (1). This tab shows a graph with some widgets under. In the graph, depending on the filter (2), the curves represent the distribution of lengths for all elements or for a chosen one. In the image on the right, the filter is set to 'Si', so grey bars in the graph represent the g(r) for silicon with whatever other species. The coloured lines represent in green and dark grey the length distribution for silicon with silicon and silicon with hydrogen, respectively.

The range of x axis of the graph is modified by the two spin buttons (3). The integration step is tune with the last spin button of the line. The lower the value, the cruder will be the g(r).

One can highlight a region in the graph, using the range buttons (4). The area is drawn in violet on the graph. Below the range buttons (4), there are two measurement information detailing the number of pair integrated in the region, divided by the number of nodes of this element (giving a clue on the average number of neighbours). The second measurement provides the mean distance corresponding to the highlighted picks. On the graph the values of the picks are printed.

A check button (5) is provided to highlight on the rendering area the nodes that correspond to the lengths in the highlight region of the graph.

Playing with colours and light↑ Return to top

V_Sim stores colours in a combobox widget. Add a colour can be done by selecting the first row in this widget and adjusting then a new colour. Each color is defined by its 3 r(red) g(green) b(blue) components (each one being between 0. and 1.). The program may use the a(alpha or opacity) channel, but this is not very recommended since some strange artifacts can appears because of a lack of drawing ordering. Values may also be changed using some range button beneath the combobox. To add the new colour, click then on the "+" button besides the range ones.

However, the color of a given pixel will be modified by lighting (and fog: see above)

Here is the description given in the "OpenGL red book" (OpenGL Programming Guide _ Addison-Wesley Publishing Company)

The OpenGL lighting model considers the lighting to be divided into four independent components: ambient, diffuse, specular and emitted.

The ambient component is the light from that source that's been scattered so much by the environment that its direction is impossible to determine - it seems to come from all directions. Backlighting in a room has a large ambient component, since most of the light that reaches your eye has bounced off many surfaces first. A spotlight outdoors has a tiny ambient component; most of the light travels in the same direction, and since you're outdoors, very little of the light reaches your eye after bouncing off other objects. When ambient light strikes a surface, it's scattered equally in all directions.

Diffuse light comes from one direction, so it's brighter if it comes squarely down on a surface than if it barely glances off the surface. Once it hits a surface, however, it's scattered equally in all directions, so it appears equally bright, no matter where the eye is located. Any light coming from a particular position or direction probably has a diffuse component.

Specular light comes from a particular direction, and it tends to bounce off the surface in a preferred direction. A well-collimated laser beam bouncing off a high-quality mirror produces almost 100 percent specular reflection. Shiny metal or plastic has a high specular component, and chalk or carpet has almost none. You can think of specularity as shininess.

Emitted light is the simplest - it originates from an object and is unaffected by any light sources.

The program has installed one light source (up right back you!) and the lighting modifies each of the rgb component by using 5 factors:

Drawing box and axes↑ Return to top

From version 3.4.0

You can draw the box around the system by selecting the check-box located in the sub-panel Box/Axes, another check-box is available to draw the axes. One can control their thickness, their colour and their line pattern. The color can be added to the list of known colours with the '+' button.

Playing with fog↑ Return to top

Fog is the process in which the nominal color is progressively mixed with the fog color as a function of its distance from the eye.

                0                                           1
eye :) ----->   [xxxxxxxxxxxxxx OBJECT xxxxxxxxxxxxxxxxxxxxx]
                        ^                        ^
                        |                        |
                        |                        |
                        start                    |

There is no fog for distances nearer than start Fog begins at start, is complete at end.

You can play with start and end values:

You can also choose fog color. Use background to have nice fog.

Display a legend↑ Return to top

From version 3.5.0

In the "axes" subpanel, one can check a box to display a legend in the rendering window. This legend display the list of declared elements, their current representation, their name and the number of corresponding nodes.

The legend in also exported in SVG.

Browsing through current directory↑ Return to top

From version 2.3-1

In the 'Browser' subpanel, all valid files for the current rendering method, are listed and Bitmapcan be selected. The directory scanned is the current working directory, but it can be changed using the button on the left (3). Using the zoom in button there, it is also possible to show a recursive browsing inside the directories (as shown on the screenshot). The listed files can be restricted to some using the filter (2), on top. This filter try to match names with the '*' character as a wild card.

Files to rendered can be selected, by checking the box in the left column. Then with the arrows (4), one can quickly browse through these files. Double clicking on a file select it and render it also. Use the buttons (5) to select all or unselect all files.

The elements on (6) are used to automatically load selected files one after another. This is convenient to view like an animation. To do it, click on the play button. All action are still working during the playing. For instance, one can still move the camera, pick an atom, change a plane position... There are three possible ways to play the selected files. The is to return to first file when the last is reached. The second is to stop when all files have been reached and the last is to play then back and forward.

The button (7) is used to dump all the selected files in the browser. When the directory and the file name is specified, a '%0xd' is required in the name to be replaced by the number of each exported file. For example if toto%03d.pdf is specified, the program will dump all selected files with name like this : toto000.pdf, toto001.pdf...

From version 3.5, two arrows (next and back) have been added to navigate between already opened directories, as in a file explorer.

Colourise nodes - basics↑ Return to top

From version 3.0.0

V_Sim has the ability to override the color of elements and to colourise node per node when an external data file is loaded. This file is a simple ascii file with figures in columns. It can have as many columns as one wishes, but the number of lines should match the number of nodes. Go to the "colourise with data" subpanel and check the checkbox (1) to use this functionality. Then open a file using the button (2) or check the other "Auto load" checkbox. This last box is used to automatically load an associated data file whenever an atomic file is loaded. V_sim then tries to match the atomic file name, substituting the extension with dat.

The number of read columns is printed in the little status bar at the bottom of the subpanel.

From version 3.5, it is also possible to use the colourisation without specifying an external file. See the "choose a shade" part further for details.

Colourise nodes - normalise data↑ Return to top

The loaded data can have whatever range possible. But to transform these values to colours, they must be transformed to [0;1]. This is done in the normalise process (1). It can be done automatically (default) or boundaries for the linear transformation can be given by hand (2). When the transformation is done automatically, in each columns, minimum value is transformed to 0 and maximum is transformed to 1. On the contrary, when set manually, boundaries are valid for all columns. Values are clamped into [0;1] in manual mode.

A little array is also given to remind the minimum and maximum values in each columns (3).

Colourise nodes - choose a shade↑ Return to top

From version 3.2.0

Once input data are transformed into [0;1], they can be used to colourise nodes. One can use preset shades (variations are read from coloumn 1 by default), see (1). Or one can define the linear transformation from input data to colours. Colours can be coded into RGB (red-green-blue) or into HSV (hue-saturation-value). Each channel is then a linear combination of input data: for instance in the given screenshot, hue (H) is equal to 0.67 - 0.67 * (values read in column 1), whereas saturation (S) is a constant set to 1.

It is possible then to create complex shade or to directly choose the colours from the input file: create then a file with three columns, each one for RGB for instance, and set R=0+1*col1, G=0+1*col2 and B=0+1*col3. If there is only one column implied in the transformation, a small representation of the resulting shade in drawn.

From version 3.5, it is possible to choose the x, y or z coordinates of nodes as a data input for the colourisation. In that case a data file is not necessary.

Colourise nodes - post processing↑ Return to top

From version 3.2.0

The first post-processing tool is used to hide nodes depending on values read from one column. To do it, check the "hide elements" box, choose the column from which values are read and set the upper bound for drawn nodes.

The second processing tool can be used to change the size of each node according to external data. To do this, check the second box and choose a column of the input file.

Colourise nodes - command line options↑ Return to top

From version 3.2.0

Draw planes - basics↑ Return to top

From version 3.1.0

One or several planes can be drawn. These planes can be fully opaque or has a degree of transparency. They can be use to highlight a region or to hide nodes. To enable the plane mode, go to the "Drawing planes" subpanel and check the appropriated checkbox.

Plane definitions are given as a list. To change some of the geometric definition, select one or several planes and use the buttons (2). The normal line gives the coordinates of the normal vector to the plane. The distance line gives the distance between the plane and the origin of the box. Finally a select element gives the opportunity to change the colour among preset ones or to choose a new one. To use the hide capability of a plane, check the hide checkbox on its line. It hides all nodes on one side of the plane. To hide the other side, check the invert checkbox. Planes are not necessary rendered to hide element.

The choice on (1) is available when several planes are drawn. It set how they interact with each others when hiding nodes. In "union" mode, a node hidden by at least one plane is actually hidden, whereas in "intersection" mode, a node must be hidden by all planes to be actually hidden.

Finally, the button (3) is used to make the camera looks in the direction of the normal of the selected plane. It can be convenient to set the view following Miller's indexes.

Draw planes - other tools↑ Return to top

From version 3.2.0

The tab called "advanced tools" is used to animate one plane. Select one, then choose the minimum distance, the maximum distance and the step then click on the play button. The distance characteristic of the selected plane is then automatically varied in the given range. All other actions are still possible during this animation, especially the observe action.

The last tab (file tools) is used to load or to save a plane file.

Draw planes - command line options↑ Return to top

From version 3.2.0

Display surfaces - Overview↑ Return to top

From version 3.1.0

This module allows you to visualise surfaces along with a previously loaded Atomic or Spin configuration. To display surfaces in the currently loaded config, check the "Use isosurfaces" box in the "Isosurfaces" subpanel. Surfaces can be drawn directly from their polygons description or they can be interpolated from a scalar field.

The description of the file format used to describe polygons of one or several surfaces is detailled on the page about formats. The description of scalar field (or potential files) is also done on this page. With the help of the ETSF plug-in, files respecting ETSF specifications for densities can be loaded.

It is possible to create a .surf file using pot2surf or combine several .surf files into a single .surf file using the surf file merger. To do it, click on the "convert" button.

Either surf files or density files are loaded using the "load" button. If the box (1) is checked, whenever a configuration is loaded V_Sim try to load a surface or a density file with the same name, replacing its extension by .surf or .dat.

Its is possible to load several files at one time. All loaded ones are present in a treeview, where their types and names are printed. In case of scalar field files, the mininum and the maximum values are reminded (2). For each surface, the check box in the column (3) is used to draw it or not. Use the buttons (8) to check or uncheck all surfaces.

The next column (4) is used to print the value of the potential from which the surface has been created. This value is editable in the case of scalar field files. To do it, click on the value and change it manually (all editable cells are printed in blue). On can change the colour of a surface or of all surfaces, using the buttons (6). The second button (change all surfaces colours) has a special behaviour. If a surface is selected, all surfaces of the same file are also changed. If nothing is selected, then all surfaces from all files are changed. More over, the colour property is associated to the surface name, so two surfaces share the same name, changing the colour property of one will affect the colour of the other. As potential values, names are editable by clicking in the cell.

The buttons (7) are used to add or remove surfaces. Addition is only possible for scalar field files. To do it, select the file in the tree view and click the "+" button. It will create a surface will the mean value of potential. Change it by clicking on the value and setting it manually. The remove button works for both surface files and scalar field files. When using it, surfaces are removed from memory and the files are left unchanged. Removing a file from the treeview removes all depending surfaces.

The box (5) can be used when the system lags because of numerous transparent surfaces. When unchecked, surfaces are not redrawn when the camera is moved with the mouse. It leads to graphical artifacts that disappear as soon as movement with the mouse is stopped.

Display surfaces - pot2surf↑ Return to top

From version 3.1.0

The pot2surf tool allows you to create isosurfaces given density data. It can be found by clicking the "Convert" button under the "Isosurfaces" panel. In order to use it, it's first needed to load a .pot file which will be immediately parsed by V_Sim to retrieve its min and max potential values. You can then set surfaces to build using the "+" button. A default value for the surface and a default name are automatically set for the surface, but you can change them by double clicking them. All surfaces names should be unique and your surfaces values shouldn't be the exact pot_min or pot_max values because pot2surf will fail if it can't build one of the surfaces. Once you've specified surfaces to build, you must select a .surf file to write. You can then click the "Build" button to build the target .surf file you specified. An option allows you to make the newly created file autoload in V_Sim's "Isosurfaces" panel. You can also save/load a pot2surf configuration as an instruction file using the toolbar buttons.

Display surfaces - Surf file merger↑ Return to top

From version 3.1.0

The surf file merger allows you to build a single .surf file from multiple ones. It can be found in a tab next to the pot2surf module. To create a new surf file, you need to load each file one after another (like a movie) on the top area of the window. V_Sim automatically parses the surf file you selects to find the surfaces that are contained within the selected file. you can then add surfaces to the bottom area by clicking the "+" button after having selected surfaces in the top list (you can even ctrl or shift-select them). Once you've finished adding surfaces, click the "Build" button to generate a new .surf file ready to load in V_Sim.

Display surfaces - Command line options↑ Return to top

From version 3.3.0

Draw scalar fields as colour maps↑ Return to top

From version 3.3.0

When a scalar field is loaded, it is possible to draw a coloured cutting plane. Go to the 'Coloured maps' subpanel, having already loaded a scalar field in the 'Isosurfaces subpanel' and having created a plane in the 'Planes' subpanel. None of the two previous modules need to be activated, just create a plane and load a scalar field. Then, they will be available in the combobox selectors. To draw the coloured map, click on the 'build' button. The map remains as long as the plane and the scalar field are loaded.

A legend is drawn in addition to the coloured map, showing the colour range. On this legend, two lines are drawn to represent the values of the minimum and maximum values currently rendered in the cutting plane. From version 3.6, additional smaller lines are drawn to represent the values of the isolines, if any.

The colour interpolation is a simple linear one, so loose density mesh may result in poor colour contours.

Advanced options↑ Return to top

From version 3.3.0

Different options are available to tune the map:

Exportation options↑ Return to top

From version 3.5.0

It is possible since version 3.5 to draw as many map as required, using the "+" button (one can remove maps using the "-" button). All maps share the same scalarfield and shade colourisation but are projected on different planes. From version 3.6, the contour values are common to all planes at once.

One can save any map into a PDF file or a SVG file. The legend is not exported yet, but the contour are there.

Command line options↑ Return to top

From version 3.3.0

Command line options for the coloured maps are:

Show geometry differences between two files↑ Return to top

From version 3.5.0

When studying geometry evolution, it can help to visualise the moving nodes. It is possible by printing arrows showing the displacements of nodes. To do it, check the box (1). Then, each time a new file is loaded, V_Sim will substract position of nodes two by two (using the node ordering of the input file), taking into account the periodic boundary conditions (if any). If the two files don't have the same number of nodes, the error is silently ignored.

The geometry differences are drawn by arrows centered on previous node positions. The length of the arrow is proportional to the displacement. For the fraction of the biggest displacements, the length is printed beside the arrow.

There are several keys in the resource file to handle the scaling of arrows.

From version 3.6, checking the box (2), one can ask V_Sim to reorder the new file with the previous. Nodes of the new file are re-indexed by matching the closest node in the previous file.

From version 3.6, when exporting in ASCII, the values of all displacements are dumped as a meta data information.

Show paths described by a set of files↑ Return to top

From version 3.6.0

When studying geometry evolution, like diffusion, saddle points..., V_Sim can help to visualise the paths used by the nodes to move. Like the geometry differences, this is a multi-file action. Each time a new file is loaded, V_Sim can add the displacements of each node to a set of lines representing the displacements. To do it, toggle the button (2). When one want to change the file but not extend the path, simply uncheck this button (2). Paths are displayed as long as check button (1) is active. To clear the current paths, click on button (3). When (2) is toggle, it is convenient to use the browser to extend the path. In that case, the browser displays a warning message that displacements will be saved. Changing directory automatically untoggle path recording.

If the file has support for total energy value (see exporting in ASCII), the paths can be colourised with a colour scheme (4) according to the energy of the system at a given position.

The XML file format of V_Sim can store existing paths or load previously saved ones using the buttons (5).

Bitmap exportations↑ Return to top

V_sim can export to bitmap images. Some vectorial formats are available (PDF for instance) but they are just containers for bitmap data. During exportation, it is possible to choose a different size compared to the one used by the view (1). The rendering is done into memory and will not use the hardware capability of the video card. This may imply slowness for big exportations.

ASCII exportations↑ Return to top

It is also possible to export any loaded file to the ASCII format (native text format of V_Sim with bounding box capability). This exportation can be interesting after having moved the atoms with the interaction move action (see the manual).

By default the unit used to export the coordinates are the one currently in use. There are several options for this format:

From version 3.6, in case of a difference between two files the differences per node are exported as a keyword.

XYZ exportations↑ Return to top

From version 3.5.0

The XYZ exportation follows the same behaviour than the ASCII exportation, with less options due to the constraints on the format.

CIF exportations↑ Return to top

From version 3.6.0

Using OpenBabel, it is possible to export in all format supported by the library. The format is selected by the extension used for the file.

Using a command line exportation with OpenBabel is typically done by:

./v_sim -o fileFormatId=1 -e example.cif example.ascii

ABINIT exportations↑ Return to top

From version 3.6.0

One can generate an ABINIT input file, regarding the crystal part.

Vectorial exportations↑ Return to top

From version 3.4.0

Introduced in version 3.4.0, the SVG allows a basic vectorial exportation. It requires Cairo to work and should be compiled at build time. Currently, it only supports the exportation of atoms (no spin), the bounding box, the pairs and the axes. The pairs exportation does not follow the user choices of style, but colours are respected.

From version 3.6, the fog is supported. The colourisation and post-treatment comming from a data file is also supported.

Scripting capabilities↑ Return to top

From version 3.6.0

When compiled with the PythonGI plug-in, one can load (2) and execute a Python script directly from the user interface in a special tab (1). Scripts should begin with:

from gi.repository import v_sim

To acces the current rendered VisuData object, one can use the following lines:

# To get the rendering window.
render = v_sim.uiMainClass_getDefaultRendering()
# To get the rendered object.
data = render.getVisuData()

Parameters file↑ Return to top

It is a file which contains some default parameters. It is read ONCE at startup. These options are relative to the interface and not the rendering itself.

When V_Sim starts,

During a V_Sim session, NO parameter file will be read! However, you can save current parameters in any file of your choice. To do it, click on the 'config. files' button on the command panel and choose the 'parameters' tab. A full list of parameters is available on the sample page.

Resources file↑ Return to top

This file is made to be able to redraw exactly a view with the same camera orientation, element colours... So it is convenient to save several of these files in different places, especially in archives.

When V_Sim starts,

During a V_Sim session, you can scan any resource file (with any name). You can also save current resources in any file of your choice. To do it, click on the 'config. files' button on the command panel and choose the 'resources' tab. A full list of resources is available on the sample page.

It is also possible to force a given file (i.e. a file with a name different from v_sim.res) using the following command line option (since 3.4.0):